Aminet 21

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 21 / Aminet 21 (1997)(GTI - Schatztruhe)[!][Oct 1997].iso / Aminet / util / libs / DigNet.lha / dignet / developer / dignet.doc

Wrap

Text File | 1997-08-23 | 48.9 KB | 2,021 lines

TABLE OF CONTENTS dignet.library/---notes--- dignet.library/---resourcetracking--- dignet.library/AbortNet dignet.library/AllocNet dignet.library/CallModemDP dignet.library/CallModemDT dignet.library/CaptureTextEnd dignet.library/CaptureTextStart dignet.library/ConverseText dignet.library/ConvertModemString dignet.library/FlushNet dignet.library/FreeNet dignet.library/GetBaudrate dignet.library/GetBitwidth dignet.library/GetCurrentDevice dignet.library/GetCurrentUnit dignet.library/GetHandshake dignet.library/GetIOmsg dignet.library/GetModemStatus dignet.library/GetNetport dignet.library/GetParity dignet.library/GetStopbits dignet.library/HangupModem dignet.library/InitIOEXT dignet.library/InitModem dignet.library/ObtainNet dignet.library/ParseConnect dignet.library/QueryNet dignet.library/ReadIOEXT dignet.library/ReadNet dignet.library/ReadString dignet.library/SetBaud dignet.library/SetBitwidth dignet.library/SetDefault dignet.library/SetHandshake dignet.library/SetParity dignet.library/SetStopbits dignet.library/StopWaiting dignet.library/Timeout dignet.library/WaitModem dignet.library/WaitText dignet.library/WriteNet dignet.library/WriteString dignet.library/RTAbort dignet.library/RTCheck dignet.library/RTFlush dignet.library/RTHighestID dignet.library/RTKillNet dignet.library/RTNetInfo dignet.library/RTNumberofNets dignet.library/---notes--- dignet.library/---notes--- From version 4 you are not allowed to open the library from a task, only a process. This shouldn't cause any problems with normal usage (only lowlevel programs are tasks such as devices etc.). The reason is that the arexx host capability is created as a subprocess of the process calling the library. From AREXX you should NOT open this as an arewxx library. You should in fact use this library as an host which means that you address the port (DIGNET) just like with for instance RexxMast and other arexx capable applications. This may seem to be confusing, but look at the provided demo script to see how. All AREXX comands are case-insensitive. dignet.library/---resourcetracking--- dignet.library/---resourcetracking--- In dignet.library version 3+ you will find special functions for resource tracking. All functions that has something to do with resource tracking begin with the letters RT. They are not within the safty call procedure as the other functions are so you should be very careful when using those. You can now create your own RT tools for the dignet.library. NOTE: You should not use these functions as an replacement for the ordinary functions. The arguments is NOT compatible. They should only be used for debug reasons. If you don't know what you're doing you are more or less guaranteed a system crash. You have been warned. As the other functions are very much "protected" the RT functions are much more sensitive. PROCEDURE: You should always use the RTCheck() function first. If this function return FALSE there is a mismatch in the resource list and alloclist. The system is unstable. If RTCheck() return TRUE you should check how many nets are available with the RTNumberOfNets(). If null exit. Alternativly and recommended you could use the RTHighestID() to find the highest net ID used. Then you should use the RTNetInfo() and check parse the list until you get to the highest ID (maximum 1024). If the DNRT_TASKSTATUS is FALSE you have resources that you can free. You can then use RTKillNet() on the current ID number or dump information to a console or file. You can use RTAbortNet(), RTFlushNet and RTNetInfo() on a healthy task. dignet.library/AbortNet dignet.library/AbortNet NAME AbortNet -- aborts the device's current IO action SYNOPSIS error=AbortNet(net) a0 ULONG AbortNet(APTR); FUNCTION This function will abort the iorequests at the device. All iorequests are stopped immediatly. Read the serial.doc for more information on how this works. From version 3 this function doesn't flush the net any longer. Use the FlushNet() function for that. INPUTS net - ptr. to a valid net structure RESULTS error - return null or an errorcode NOTES From version 3 this function no longer flushes the net. AREXX ABORTNET '"'<net>'"' EXAMPLE BUGS SEE ALSO FlushNet(), serial.doc dignet.library/AllocNet dignet.library/AllocNet NAME AllocNet -- Allocates a private structure to use with the other functions SYNOPSIS net=AllocNet(devicename,unit) a1 d0 APTR AllocNet(STRPTR,UWORD); FUNCTION To use any of the functions in this library you need to allocate a net structure. This structure is private. The structure information is needed for the other functions to know where and what to read/write. It also allocates memory to use with IOEXT, message structures and so on. Additionally the device get flushed and aborted at startup to make a clean start for user. When this function returns true you are ready to use the device (Note: opposite of a OpenDevice() call). CHANGES: From version 3 of this library this function no longer inits the device with a default setting (see SetDefault()). That means it use the setup you have defined in the serial preference program on your system. However if you find it difficult to configure it correctly you could use the SetDefault() function to set the device to a "safe" setup which supports highspeed and 8-bits transfers. INPUTS devicename - ptr. to the device name you want to open [0] unit - unit number RESULTS net - ptr. to a private structure or NULL if any errors. NOTES NOTE: Devices returns NULL when succeeded. This library function will not reflect this result. It will return NULL only if a failure occured such as out of memory or the port couldn't be created or the device couldn't be opened. There is currently no way within the library to find the exact cause of the problem. However, most other functions in this library returns NULL when things went well since they reflect the io_error field. Keep this in mind! NOTE WELL: Max length of taskname and device name is 127 (including the null byte termination). The names are copied to a private buffer. Max open nets is currently 1024 which really is more than enough (not to sound like Bill Gates, but a device can only have 256 open units and you would need to open 4 devices and use all the units to exceed the max limit of this library - just to be on the safe side..) AREXX ALLOCNET "<devicename>" <unitnumber> RESULT=NetNumber (not address) EXAMPLE Net=AllocNet("serial.device",0) or move.l DignetBase,a6 ;library base in a6 lea DeviceName,a0 ;device name in a0 moveq #0,d0 ;unit number in d0 jsr _LVOAllocNet(a6) ;call function move.l d0,Net ;store pointer beq Error ;if null go to error handling BUGS An exact cause of an error should be implemented. SEE ALSO FreeNet(), SetDefault() dignet.library/CallModemDP dignet.library/CallModemDP dignet.library/CallModemDT dignet.library/CallModemDT NAME CallModem -- Do the dialup and check procedure for you when dealing with modems (version 3). SYNOPSIS baud=CallModemDP(net,number,buffer) a0 a1 a2 ULONG CallModemDP(APTR, STRPTR, APTR); baud=CallModemDT(net,number,buffer) a0 a1 a2 ULONG CallModemDT(APTR, STRPTR, APTR); FUNCTION These functions will do the whole procedure for you to dial up a number, check the result and return the connect rate. If successful CONNECT the functions return the baudrate. If NULL is returned you should check your buffer. It will contain what the modem returned such as "NO CARRIER", "NO ANSWER", "BUSY", "NO DIALTONE", "ERROR", VOICE", "DELAYED" etc. "CONNECT ..." is the only valid return string for these functions to make them return true. The baudrate is extracted from the connect string. Internally they use the ParseConnect() to get the baud rate, but they copy the string first since ParseConnect() makes the buffer invalid. Your buffer is due to the internal copy valid after this call and you can use the ParseConnect() on it if you need to. If you want to use touch tone dial you can use CallModemDT(). If you of some reason need pulse dial, call the CallModemDP(). The functions are compatible and you should let the user of your program deside which one to use. CallModemDT() is the most common function to call. The functions has 30 second timeout limit. If no answer to the dialup is received within 30 seconds or something locks up, the functions will return with error. Currently there is no way to terminate a dialup in progress from the library. You can however call the HangupModem() anytime to break the dial or to hangup a connection. INPUTS net - ptr. to a valid net structure number - null terminated string that contains the number to dial, f.ex. "12345678"[0] buffer - ptr. to a buffer to contain the result. Must be minimum 16 bytes. RESULTS baud - the baudrate at connect or NULL if any error. Check your buffer if NULL is returned. AREXX CallModemDT '"'<net>'"' <phonenumber> CallModemDP '"'<net>'"' <phonenumber> These functions do not work properly from arexx yet. NOTES EXAMPLE move.l Net(pc),a0 lea Number(pc),a1 lea Buffer(pc),a2 Call CallModemDT move.l d0,Baud beq .error [...] Number dc.b "12345678",0 Buffer dcb.b 16,0 BUGS You should have a possibility to terminate a dialup in progress before the phone in the other end picks up the line. You can with having a subtask sending a HangupModem(), but this isn't reliable timewise. SEE ALSO HangupModem(), ParseConnect() dignet.library/CaptureTextEnd dignet.library/CaptureTextEnd NAME CaptureTextEnd -- Stop capture to a file (version 4) SYNOPSIS status=CaptureTextEnd(net) a0 BOOL CaptureTextEnd(APTR); FUNCTION To end a capture you must call this function. Resource tracking will end the capture if you call FreeNet() as well. If there is no capture in progress you will get returned FALSE, otherwise TRUE. You must also call this function if you want to start capturing to another file as you can only capture to one file at the time. INPUTS net - ptr. to a valid net RESULTS status - TRUE if file got closed, FALSE if no capture was enabled. AREXX CAPTURETEXTEND '"'net'"' SEE ALSO CaptureTextStart() dignet.library/CaptureTextStart dignet.library/CaptureTextStart NAME CaptureTextStart -- Start capture of bytes sent or received (version 4) SYNOPSIS status=CaptureTextStart(net,filename,mode) a0 a1 d0 BOOL CaptureTextStart(APTR,STRPTR,UWORD); FUNCTION With this function you can capture bytes sent or received on the serial port. The function will open a new file or append to an already existing file. All data transfered or received on the net is saved to this file as well. The function will return TRUE if file is ok, otherwise you will get false. If you are already capturing you will get returned FALSE. The file is closed (or capture stopped) by calling the function CaptureTextEnd(). The resource tracking will end the file for you when calling FreeNet(), but please do program properly. You can either append a file using DNCAPTUREAPPEND as mode or create a new file by using DNCAPTURENEW. Binaries (raw) chars will be captured too. INPUTS net - ptr. to a valid net filename - ptr. to a null terminated string containing path and filename mode - DNCAPTUREAPPEND or DNCAPTURENEW RESULTS status - true if file is ok and you don't capture already, false if file couldn't be created (due to error in path etc.) or if you are already capturing to a file. NOTES Some functions may "swallow" their bytes sent or received (such as InitModem() for instance). Support for these functions may be implemented in future. You can only capture to one file at the time per net. AREXX CAPTURETEXTSTART '"'Net'"' <mode> <filename> mode = 0 -> new file mode = -1 -> append file EXAMPLE BUGS SEE ALSO CaptureTextEnd(), dignet/dignet.i|h dignet.library/ConvertModemString dignet.library/ConvertModemString NAME ConvertModemString -- convert a standard modem string to binary/ascii (version 3) SYNOPSIS newstring=ConvertModemString(string) a0 STRPTR ConvertModemString(STRPTR); FUNCTION This function converts strings used for modem such as "ATZ\r" to its binary meaning. "ATZ\r" would become "ATZ"(13) in this example. The function uses the same string buffer as you gave because a convertion will always make the string shorter than the original string. It also nullterminates the new string. If you allocated the string you should use the original length to deallocate the new string. Currently this function only supports these C-style string commands: \b - backspace \e - escape \f - form feed \n - linefeed \r - carriage return \t - tabulator The string you provide can contain binary codes as well. It only converts "\*"-sequences and stops only when it finds a null byte. INPUTS string - ptr. to a string you want to send the modem RESULTS newstring - ptr. to the converted string (same address as the string you provided with the function). NOTE: If string is unchanged you should check the string ptr. you gave or the string content. It will exit if a0=null AREXX CONVERTMODEMSTRING <string> RESULT=newstring NOTES EXAMPLE NewString=ConvertModemString("ATZ\r") NewString <- ATZ(13)(0) BUGS SEE ALSO InitModem() dignet.library/ConverseText dignet.library/ConverseText NAME ConverseText -- Waits for a string to be received and then send a string (version 4) SYNOPSIS error=ConverseText(net,waitstring,putstring) a0 a1 a2 ULONG ConverseText(APTR, STRPTR, STRPTR); FUNCTION If you have seen NComm's script language you will probably recognice this function. It waits for a specific string (case-sensitive) and when it get the string it sends a string. Very useful if you want to make dialup scripts (eg. you get login: and then you can send your login name etc.). To break waiting you can call the StopWaiting() function. INPUTS net - ptr. to a valid net waitstring - ptr. to a null terminated string to wait for putstring - ptr. to a null terminated string to send RESULTS error - null if ok, else IO error NOTES The 'waitstring' is case-sensitive. EXAMPLE BUGS SEE ALSO WaitText() dignet.library/FlushNet dignet.library/FlushNet NAME FlushNet -- Flushes the net buffers. Useful with AbortNet() (version 3) SYNOPSIS error=FlushNet(net) a0 ULONG FlushNet(APTR); FUNCTION This function flushes the IO buffers used by a net. It's useful after you AbortNet() a net to clean up garbage retuned on the port buffers. From version 3 the function als have a safty routine after a flush. It reads the net for garabge and put it to a nil function of the library. That should guarantee pretty much that when this function returns the buffer is empty. INPUTS net - ptr. to a valid net structure RESULTS error - NULL if ok, io_error otherwise NOTES EXAMPLE BUGS SEE ALSO AbortNet() dignet.library/FreeNet dignet.library/FreeNet NAME FreeNet -- Frees and cleanup the structure allocated with AllocNet() SYNOPSIS error=FreeNet(net) a0 LONG FreeNet(APTR); FUNCTION This function will free the structure allocated with AllocNet(). It will also flush, abort, wait and close the device and then free memory allocated with AllocNet(). From version 2.1 this function now returns an error code. Null if ok, -1 (DNETERROR_WRONGNET) if you tried to free a net structure that had wrong pointer. The error result is for debug purposes. You use it optionally, but you should test it before a public release. If you get this error you gave it the wrong net structure pointer or the net was already freed once. This feature is a bi-effect of the resource capabillity of the library implemented in version 2.1. INPUTS net - ptr. to a valid net structure RESULT error - null if ok, dneterror_wrongnet if wrong net structure was tried to get freed. EXAMPLE error=FreeNet(net) NOTES From version 2.1 this function returns an error code. BUGS SEE ALSO AllocNet() dignet.library/GetBaudrate dignet.library/GetBaudrate NAME GetBaudrate -- Returns the current initialized baudrate (version 3) SYNOPSIS baudrate=GetBaudrate(net) a0 ULONG GetBaudrate(APTR); FUNCTION This function returns the currently used baudrate from the device. This is not neccesarly the same baud speed as the modem connect with. However the baud speed should be as high as possible. INPUTS net - ptr. to a valid net structure RESULTS baudrate - usigned long integer with the device baud rate or NULL if error NOTES It does not reflect the connect speed if you use the net with a modem. See the ParseConnect() to obtain connect speed. EXAMPLE BUGS SEE ALSO SetBaud(), SetDefault() dignet.library/GetBitwidth dignet.library/GetBitwidth NAME GetBitwidth -- returns the current device used's bitwidth (version 4) SYNOPSIS bitwidth=GetBitwidth(net) a0 ULONG GetBitwidth(APTR); FUNCTION This function returns the bitwidth of the device used in net. INPUTS net - ptr. to a valid net RESULTS bitwidth - integervalue representing the bitwidth of device NOTES EXAMPLE BUGS SEE ALSO SetBitwidth() dignet.library/GetCurrentDevice dignet.library/GetCurrentDevice NAME GetCurrentDevice -- returns a pointer to device name currently used. (version 3) SYNOPSIS devicename=GetCurrentDevice(net) a0 STRPTR GetCurrentDevice(APTR); FUNCTION This function will return a pointer to the name of the device currently used by the net. You should NOT change the content of the string. You are allowed to copy the string to your own buffer. The name is correct as long as the net is valid and the above rule is followed. INPUTS net - ptr. to a valid net structure RESULTS devicename - ptr. to a nullterminated string containing the device name of the device currently beeing used. NULL if error. NOTES EXAMPLE BUGS SEE ALSO GetCurrentUnit() dignet.library/GetCurrentUnit dignet.library/GetCurrentUnit NAME GetCurrentUnit -- Returns unit number of device used (version 3) SYNOPSIS unit=GetCurrentUnit(net) a0 UWORD GetCurrentUnit(APTR); FUNCTION This function returns the unit number of the device currently beeing used by the net structure. The number is always correct if the net is valid. INPUTS net - ptr. to a valid net structure RESULTS unit - unit number or -1 if error NOTES EXAMPLE BUGS SEE ALSO GetCurrentDevice() dignet.library/GetHandshake dignet.library/GetHandshake NAME GetHandshake -- Get current handshake mode of net device (version 4) SYNOPSIS mode=GetHandshake(net) a0 ULONG GetHandshake(APTR); FUNCTION This function will return the current handshake mode of the device used in the net. See the include file for modes. NOT ACTIVATED IN 4.0 - You may use it for future compability (will return null in 4.0) INPUTS net - ptr. to a valid net RESULTS mode - see include file for handshake modes NOTES EXAMPLE BUGS NOT ACTIVATED IN 4.0 SEE ALSO Sethandshake() dignet.library/GetIOmsg dignet.library/GetIOmsg NAME GetIOmsg -- Returns a pointer to the IO msg used (version 3) SYNOPSIS iomsg=GetIOmsg(net) a0 struct iomsg * GetIOmsg(APTR); FUNCTION This function returns a pointer to a IOMSG structure used by the device. Useful if user want to use the device in a more advanced way. INPUTS net - ptr. to a valid net structure RESULTS iomsg - ptr. to a iomsg structure or NULL if error NOTES EXAMPLE BUGS SEE ALSO GetNetport() dignet.library/GetModemStatus dignet.library/GetModemStatus NAME GetModemStatus -- Returns a bool of the assumed modem state (version 3) SYNOPSIS status=GetModemStatus(net) a0 BOOL GetModemStatus(APTR); FUNCTION This function returns a bool of what it thinks the current modem state is. If false the modem is assumed offline, if true the modem is assumed to be online. The reason why it has to assume the status if because after a successful modem dial the user can turn off the modem and on again. The net structure doesn't know about this. INPUTS net - ptr. to a valid net structure RESULTS status - BOOL, true if modem is assumed online, false if assumed offline You will get FALSE if error. NOTES The function only assumes the status, it doesn't know for sure. EXAMPLE BUGS Should find a way to check the real status. Some active line or something. If some of you know, please report to kenny@bgnett.no SEE ALSO CallModem(), HangupModem() dignet.library/GetNetport dignet.library/GetNetport NAME GetNetport -- Returns the pointer to the msg port used for net (ver 2) SYNOPSIS port=GetNetport(net) a0 struct MP* GetNetport(APTR); FUNCTION This function return a pointer to the public message port used by this library. You are free to name it. You can with this function use this more advanced uses such as collecting port signals and Wait() them. No need to use this function if you don't require advanced uses. INPUTS net - ptr. to a valid net structure RESULTS port - ptr. to a message port (public). NULL if error. NOTES After a FreeNet() call the port is invalid! EXAMPLE BUGS SEE ALSO GetIOmsg() dignet.library/GetParity dignet.library/GetParity NAME GetParity -- Get current parity mode used in device/net (version 4) SYNOPSIS mode=GetParity(net) a0 ULONG GetParity(APTR); FUNCTION This function will return the current parity mode used by the device in the net structure. See include file for parity mode. NOT ACTIVATED IN 4.0 - You may use it for future compability (will return null in 4.0) INPUTS net - ptr. to a valid net RESULTS mode - parity mode used (see include file) NOTES EXAMPLE BUGS NOT ACTIVE IN 4.0 SEE ALSO SetParity() dignet.library/GetStopbits dignet.library/GetStopbits NAME GetStopbits -- returns the number of stopbits used in device (version 4) SYNOPSIS stopbits=GetStopbits(net) a0 ULONG GetStopbits(APTR); FUNCTION This function will return number of stopbits used by device. Usually it will be 1. INPUTS net - ptr. to a valid net RESULTS stopbits - number of stopbits NOTES EXAMPLE BUGS SEE ALSO SetStopbits() dignet.library/HangupModem dignet.library/HangupModem NAME HangupModem -- send break and hangup command to modem (version 3) SYNOPSIS error=HangupModem(net) a0 ULONG HangupModem(APTR); FUNCTION This function send the a break and hangup command to the modem. The string it sends is "\w\w+++\w\w\w\wATH\r". This is a standard way to hangup the modem when online. If you need to hangup the modem otherwise you should use the WriteNet() function to write your string to the modem that hang it up. The function will use 3.5 seconds on the hangup. It also sends the ATH command twice. You could take a FlushNet() after a HangupModem() call. INPUTS net - ptr. to a valid net structure RESULTS error - NULL if OK when sending, io_error otherwise NOTES Sending a break and hangup command to the modem does NOT guarantee the modem to hang up. You should check the lights on your modem if it really hung up. EXAMPLE BUGS SEE ALSO WriteNet() dignet.library/InitIOEXT dignet.library/InitIOEXT NAME InitIOEXT -- Init the IOEXT structure of a device (serial/duart etc.) SYNOPSIS error=InitIOEXT(net,newIOEXT,size) a0 a1 d0 ULONG InitIOEXT(APTR, APTR *, ULONG); FUNCTION This function will init the IOEXT and call the device function SetParameters. Only use this with devices that are compatible with the serial device (for example duart.device). Always use the ReadIOEXT() first to copy current settings of the device to your buffer. This way you only have to change some fields. If not you will have to setup the whole IOEXT struture. INPUTS net - ptr. to a valid net structure newIOEXT - ptr. to new settings (IOEXTSER structure) size - number of bytes to copy RESULTS error - reflects the io_error field. Null if ok. NOTES For C users: Use struct IOEXTSER *, but you need to add $30 to the structure's beginning since this function copy only the IOEXTSER part! Currently max number of chars to read should be 80 bytes. EXAMPLE BUGS Should perhaps used the whole IO stucture to make it more simpler for C users. SEE ALSO ReadIOEXT(), devices/serial.i|h, dignet/dignet.i|h dignet.library/InitModem dignet.library/InitModem NAME InitModem -- Inits a modem with a standard initstring (version 3) SYNOPSIS error=InitModem(net,initstring,buffer) a0 a1 a2 ULONG InitModem(APTR,STRPTR,APTR); FUNCTION The function converts the string and sends it to the net where it expect a modem to be. If no modem found it return with either timeout error or error code from the io_error field. A string could be: "ATZ\r"[0] and the function converts this to: ATZ(13) [13=Carriage Return/CR] Currently this function only supports these C-style string commands: \b - backspace \e - escape \f - form feed \n - linefeed \r - carriage return \t - tabulator Other commands will be ignored. The function copies the io_actual error code to result and the string the modem replies with to the buffer you provided so you can check or print the result (eg. OK or ERROR). Note that the buffer must be atleast 16 bytes long. If user provides a init string which dumps much data, this function will crop that stream to 16 bytes so it'll fit into the buffer. With correct use of the init string the modem should return 3 bytes OK(13). INPUTS net - ptr. to a valid net structure initstring - ptr. to a nullterminated init string (required from 3.03). buffer - ptr. to buffer. Minimum 16 bytes long. Contains modem result. RESULTS error - NULL if ok, DNETERROR_TIMEOUT if timeout (maybe no modem), or io_error in all other cases. You should check the buffer in any case. NOTES From 3.03 you MUST supply an Initstring in A1 ! The buffer you provide must be a minimum of 16 bytes long (it will never read more than 16 bytes into the buffer). This routine gives the modem 3 seconds to reply. It returns immediatly if it receives a reply from the modem. EXAMPLE To check the buffer if it is empty or not you could do (from assembler): lea Buffer,a0 tst.b (a0) beq .empty BUGS Kept only a copy of the echo from modem (the init string itself). Now it will strip the echo till there has been two CR's and then it copies the rest into the buffer. Note that due to this the function may fail (return not-null), but this works fine with USRobotics modems. Please report to our email address if you can't get this function to work with your modem. SEE ALSO CallModem(), ConvertModemString() dignet.library/ObtainNet dignet.library/ObtainNet NAME ObtainNet -- to share a net from another task (version 3) SYNOPSIS net=ObtainNet(taskname) a0 APTR ObtainNet(STRPTR); FUNCTION This function will try to find a net allocated by taskname. If success this function will return with a pointer to the netstructure. NOTE: It's never safe to use the net structure since you don't know if the net owner task frees it. You should have very special reasons to use this function, probably debug reasons or sub tasks that want to use the net. If so control the freeing with flags or similar. There will maybe be locking functions in future. INPUTS taskname - ptr. to a taskname RESULTS net - net structure if success or NULL NOTES Use this for special reasons only! EXAMPLE BUGS SEE ALSO AllocNet() dignet.library/ParseConnect dignet.library/ParseConnect NAME ParseConnect -- Converts a connect string to baudrate (version 3) SYNOPSIS baudrate=ParseConnect(buffer) a0 ULONG ParseConnect(APTR); FUNCTION This function will try to convert a CONNECT string returned by CallModem() in buffer. It then returns the integer value of the connect speed (real speed). If buffer contains error messages or is empty this function will return NULL. The buffer is considered invalid after you have used this function on it! INPUTS buffer - ptr. to the buffer CallModem() returned its connect string. RESULTS baudrate - unsigned long integer containing baudrate or NULL if invalid buffer NOTES The buffer is considered invalid after you have used this function on it! EXAMPLE BUGS SEE ALSO CallModemDT(), CallModemDP() dignet.library/QueryNet dignet.library/QueryNet NAME QueryNet -- Query the device and return number of chars that are available for read. SYNOPSIS chars=QueryNet(net) a0 ULONG QueryNet(APTR); FUNCTION Use this function before you ReadNet() the device. This function will return number of bytes that are available to read. You can parse the result directly to ReadNet(). If zero bytes the ReadNet() will abort and return immediatly. INPUTS net - ptr. to a valid net structure RESULTS chars - number of chars available to read NOTES EXAMPLE BUGS SEE ALSO ReadNet() dignet.library/ReadIOEXT dignet.library/ReadIOEXT NAME ReadIOEXT -- Copies current settings in IOEXT to a buffer SYNOPSIS ReadIOEXT(net,buffer,size) a0 a1 d0 void ReadIOEXT(APTR,APTR,ULONG); FUNCTION This function will copy current setting of the IOEXT structure used to for example to set baud rate in the serial device. The device has to be compatible with the serial device to read successfully. The reason for this is that it reads from an offset that is valid for the serial.device. If another device has its IOEXT structure at same offset this function and the InitIOEXT() function can be used. Remember to set number of bytes to copy. INPUTS net - ptr. to a valid net structure buffer - ptr. to a buffer to copy to size - number of bytes to copy NOTES Currently max number of chars to read should be 80 bytes. DO NOT use devices that are not compatible with the serial.device or the IOEXTSER structure! EXAMPLE BUGS SEE ALSO InitIOEXT(), devices/serial.i|h, dignet/dignet.i|h dignet.library/ReadNet dignet.library/ReadNet NAME ReadNet -- reads x bytes from the device SYNOPSIS error=ReadNet(net,buffer,size) a0 a1 d0 ULONG ReadNet(APTR,APTR,ULONG); FUNCTION This function will read from the device. You should first call a query function to check the number of bytes waiting and then read those into your buffer. If zero bytes this function will abort immediatly so it is safe to call it. If you ask for more bytes than are available this function will wait until the amount can be read from the port. Use AbortNet() to cancel the wait or use Timeout() to give some time to get some bytes on the port before a ReadNet() is called. This function reads byte-by-byte to not miss any chars from the buffer. INPUTS net - ptr. to a valid net structure buffer - ptr. to a buffer size - number of bytes to read RESULTS error - null if ok, else it reflects the io_error field NOTES EXAMPLE error=ReadNet(net,buffer,queryresult|timeoutresult) BUGS SEE ALSO WriteNet(), QueryNet(), AbortNet(), Timeout() dignet.library/ReadString dignet.library/ReadString NAME ReadString -- read a null terminated string from net (version 2) SYNOPSIS error=ReadString(net,buffer,max) a0 a1 d0 ULONG ReadString(APTR,APTR,ULONG); FUNCTION This function will read a string until it reaches a null termination byte or buffer overflows. Useful with the function WriteString() which sends a null terminated string to the net. CHANGES: if this function returns -1 (from version 2.1) it means buffer overflow. You should act on that and continue to read after you have cleaned up. Other non-null returns are errors returned from io_error field. Consult the serial.device documentation to get the definitions on those. INPUTS net - ptr. to a valid net structure buffer - ptr. to buffer to keep the string max - max length of string RESULTS error - NULL if OK. -1 if buffer overflow, otherwise io_error. NOTES NOTE WELL: This function returns -1 from version 2.1. It returned 1 in earlier version, but that could conflict with the dev_busy error (1). Please update your programs. Sorry for the inconvinient. EXAMPLE BUGS See notes! SEE ALSO WriteString(), QueryNet(), Timeout(), AbortNet() dignet.library/SetBaud dignet.library/SetBaud NAME SetBaud -- updeates the device with a new baudrate (version 3). SYNOPSIS error=SetBaud(net,baud) a0 d0 ULONG SetBaud(APTR,ULONG); FUNCTION Use this function to update just the baud rate. The baudrate should be an integer value, for example: baud=38400. INPUTS net - ptr. to a valid net structure baud - integer value describing the baud rate. RESULTS error - NULL if OK, otherwise io_error or -1 if a0 or d0 is null. NOTES Most devices communciating with the serial port do not support baud rates in a linear way. Read the documentation about which baud rates the device supports. EXAMPLE BUGS SEE ALSO ReadIOExt(), InitIOExt() dignet.library/SetBitwidth dignet.library/SetBitwidth NAME SetBitwidth -- Set bitwidth of transfer bytes of device (version 4) SYNOPSIS error=SetBitwidth(net,width) a0 d0 BOOL SetBitwidth(APTR,UBYTE); FUNCTION This function will set new bitwidth in IOEXT on each char transfered. Then it calls SetParameter with DoIO(). INPUTS net - ptr. to a valid net width - char width (usually 8, in some cases 7) RESULTS error - true if ok, otherwise false (0) NOTES EXAMPLE BUGS Still at beta state SEE ALSO GetBitwidth() dignet.library/SetDefault dignet.library/SetDefault NAME SetDefault -- Set default parameters to a "safe" setup (version 3) SYNOPSIS error=SetDefault(net) a0 ULONG SetDefault(APTR); FUNCTION This function will initialize the modem with considered "safe" settings. the following parameters are set: Buffer size: 8194 Flags: 7WIRE + BOGGIE + XDISABLED + NOPARITY (RTS/CTS handshaking) BAUD: 38400 (this is not the connect baud) 8 bits per char 1 stopbit This setup should work for any Amiga. If you have a slow Amiga (68000 or 68010) you should use the SetBaud() function and set baud to 19200. If you have a faster Amiga than 68030/25 Mhz you can set use the SetBaud() function to set 57000 or better. The BOGGIE and 7WIRE make sure that you can accept highspeed transfers. Without those you may get garbage. You can use the ReadIOEXT() and InitIOEXT() to change flags and more. INPUTS net - ptr. to a valid net structure RESULTS error - NULL if ok, otherwise io_error NOTES EXAMPLE BUGS The serflags was put into extflags instead. Now fixed! SEE ALSO SetBaud(), ReadIOEXT(), InitIOEXT() dignet.library/SetHandshake dignet.library/SetHandshake NAME SetHandshake -- Set new handshake protocol on device (version 4) SYNOPSIS error=SetHandshake(net,handshake) a0 d0 BOOL SetHandshake(APTR,UWORD); FUNCTION To change the device's protocol handshaking use this function for convinient. The function sets the approriate flags in the IOEXT structure and calls SetParameters with DoIO. INPUTS net - ptr. to a valid net handshake - handshake type (see include) RESULTS error - true if success otherwise false (0). NOTES EXAMPLE BUGS Still at beta state SEE ALSO GetHandshake() dignet.library/SetParity dignet.library/SetParity NAME SetParity -- Set new parity to net (version 4) SYNOPSIS error=SetParity(net,paritymode) a0 d0 BOOL SetParity(APTR, UWORD); FUNCTION With this function you can easily set new parity to the current net. You must use one of the parity modes (see dignet.i|h for modes). The new parity is triggered immediatly. INPUTS net - ptr. to a valid net paritymode - (see dignet.i for the different modes). RESULTS error - TRUE is OK, FALSE if mode is unknown or it couldn't set this parity mode to this net. NOTES EXAMPLE BUGS SEE ALSO GetParity() dignet.library/SetStopbits dignet.library/SetStopbits NAME SetStopbits -- Sets number of stop bits in IOEXT (version 4) SYNOPSIS error=SetStopbits(net,bits) a0 d0 BOOL SetStopbits(APTR,UBYTE); FUNCTION This function will set number of stop bits and call SetParameters with DoIO() for you. INPUTS net - ptr. to a valid net bits - number of stop bits (usually 1, in some cases 2) RESULTS error - true if ok, otherwise false NOTES EXAMPLE BUGS Still at beta state SEE ALSO GetStopbits() dignet.library/StopWaiting dignet.library/StopWaiting NAME StopWaiting -- Terminates a WaitModem() call (version 3) SYNOPSIS StopWaiting(net) a0 void StopWaiting(APTR); FUNCTION This function sends a terminate message to the WaitModem() function. The WaitModem() will otherwise never return if it not receive a RING string first. It may take some seconds before the function returns after the terminate message is sent. The buffer should contain "TERMINATED" if this was the reason. From version 4 this function will also break WaitText() and ConverseText(). INPUTS net - ptr. to a valid net structure NOTES Calling it with no WaitModem() waiting has no effect and is safe. EXAMPLE BUGS SEE ALSO WaitModem() dignet.library/Timeout dignet.library/Timeout NAME Timeout -- waits x seconds to receive char(s) on the device for reading SYNOPSIS chars=Timeout(net,seconds) a0 d0 ULONG Timeout(APTR,UWORD); FUNCTION You can use this function to give a device a certain amont of time to get a char or more on the port for reading. You set seconds to wait. If a char or more is received the function will return with the current amount of chars in buffer. If timeout occure it will return with NULL. Null seconds is valid, however it will just call the QueryNet() function instead and return immediatly. If you lock up waiting for chars with ReadNet() or ReadString() use the AbortNet() function. INPUTS net - ptr. to a valid net structure seconds - number of seconds to wait for timeout RESULTS chars - number of chars received before timeout or NULL if none NOTES The seconds are divided in smaller parts so the function don't have to wait a whole second to return if there are chars on the buffer. EXAMPLE BUGS It should use WaitPort() instead of Delay() + Query. Will maybe be fixed in future. SEE ALSO QueryNet(), AbortNet() dignet.library/WaitModem dignet.library/WaitModem NAME WaitModem -- Waits for a incoming modem call (3) SYNOPSIS baud=WaitModem(net,buffer) a0 a1 ULONG WaitModem(APTR, APTR); FUNCTION When you call this function the library goes into a wait mode on a modem call. The call is detected with a "RING" signal. If the modem can connect it returns the speed it connected with in a unsigned long word integer, else it will return null if it was any error such as a voice or fax call instead. The buffer contains a string the modem sends when connecting. To break the wait you need to call the StopWaiting() function on the net which is waiting. This is preferable done from a sub-task. INPUTS net - ptr. to a valid net buffer - ptr. to a buffer (min 16 bytes) RESULTS baud - the actual connect speed if success or null if any errors NOTES EXAMPLE BUGS SEE ALSO StopWaiting() dignet.library/WaitText dignet.library/WaitText NAME WaitText -- Waits for a string to be read on the port (version 4) SYNOPSIS error=WaitText(net,waitstring) a0 a1 ULONG WaitText(APTR,STRPTR); FUNCTION This function will wait until it receives a string equal to waitstring on the port. To break the waiting use the StopWaiting() function. INPUTS net - ptr. to a valid net waitstring - ptr. to a nullterminated string to wait for (may contain binaries) RESULTS error - null if ok, else IO error NOTES String is case-sensitive. EXAMPLE BUGS SEE ALSO ConverseText() dignet.library/WriteNet dignet.library/WriteNet NAME WriteNet -- Writes x bytes to the device SYNOPSIS error=WriteNet(net,buffer,size) a0 a1 d0 ULONG WriteNet(APTR,APTR,ULONG); FUNCTION This function write a number of bytes (really a copy) from a buffer of size x. The function returns immediatly. INPUTS net - ptr. to a valid net structure buffer - ptr. to a buffer taht contains bytes to write size - number of bytes to write RESULTS error - reflects the io_error field. Null if ok. NOTES EXAMPLE error=WriteNet(net,buffer,3351) BUGS In earlier versions there had to be implemented a delay of 20/50 of a second to get all chars read from the io buffer. This is fixed for the version 2 release. The library now read and writes byte-by-byte to not loose any chars. SEE ALSO ReadNet() dignet.library/WriteString dignet.library/WriteString NAME WriteString -- Writes a nullterminated string to net (v.2) SYNOPSIS error=WriteString(net,string) a0 a1 ULONG WriteString(APTR,STRPTR); FUNCTION This function is pretty similar to WriteNet(). In fact this function is just a pre-function to WriteNet(). It counts the number of chars in the string until zero is found and the calls the WriteNet() function with length as parameter. Read about WriteNet() for more info. The result code is actually returned be WriteNet() and reflects the io_error field. Null if ok. INPUTS net - ptr. to a valid net structure string - ptr. to a null-terminated string RESULTS error - reflects the io_error field. Null if ok. NOTES EXAMPLE BUGS SEE ALSO ReadString() dignet.library/RTAbort dignet.library/RTAbort NAME RTAbort -- Tries to abort an allocated net (version 3) SYNOPSIS RTAbort(ID) d0 void RTAbort(ULONG); FUNCTION This function will try to abort a net. If the net isn't in use the function will return immediatly. There is no saftcheck on the pointers. INPUTS ID - ID of a net NOTES EXAMPLE BUGS SEE ALSO RTNetInfo dignet.library/RTCheck dignet.library/RTCheck NAME RTCheck -- Checks the count list for mismatch (version 3) SYNOPSIS status=RTCheck() BOOL RTCheck(void); FUNCTION This function check the resource tracklist and the opennet counter for any mismatch. If this function return FALSE there is a mismatch in the count lists. That could mean some net isn't properly killed (invalid pointer was given to RTKillNet() or something like that). If there is a mismatch you have to cleanup manually by finding the net that should be killed and then FreeNet() it. You do so at your own risk! RESULTS status - TRUE if ok, otherwise FALSE and system is in risk. NOTES EXAMPLE BUGS SEE ALSO RTNumberofNets() dignet.library/RTFlush dignet.library/RTFlush NAME RTFlush -- Tries to flush an allocated net (version 3) SYNOPSIS RTFlush(ID) d0 void RTFlush(ULONG); FUNCTION This function will try to flush an allocated net. You should check for the existance of the net by using the RTNetInfo() function first. INPUTS ID - ID of a net NOTES EXAMPLE BUGS SEE ALSO RTNetInfo() dignet.library/RTHighestID dignet.library/RTHighestID NAME RTHighestID -- Return the highest ID number (version 3) SYNOPSIS HighestID=RTHighestID() ULONG RTHighestID(void); FUNCTION This function will return the highest ID number available. If there are no nets if will return NULL. This function is useful when you will parse a list. RESULTS HighestID - highest ID number or NULL if no nets are allocated NOTES EXAMPLE BUGS SEE ALSO RTNetInfo() dignet.library/RTKillNet dignet.library/RTKillNet NAME RTKillNet -- Tryes to kill an allocated net (version 3) SYNOPSIS RTKillNet(ID) d0 void RTKillNet(ULONG); FUNCTION This function will try to kill an allocated net. You should however use the function RTNetInfo() first to check if the netowener task is in tasklist or not. You shouldn't kill a net that is owned by a healthy task. If the net ID isn't valid the function will return immediatly. INPUTS ID - Net ID. NOTES DO NOT use this function on a healthy task! EXAMPLE BUGS SEE ALSO RTNetInfo(), RTAbort(), RTFlush() dignet.library/RTNetInfo dignet.library/RTNetInfo NAME RTNetInfo -- Returns vital information about a net ID (version 3) SYNOPSIS success=RTNetInfo(buffer,ID) a0 d0 BOOL RTNetInfo(APTR,ULONG); FUNCTION This function will copy vital information from the private RT structure in the library to a public structure (see dignet/dignet.i|h). If the net ID isn't valid (eg. isn't used) the function will return immediatly with FALSE in bool. INPUTS buffer - ptr. to a buffer that contains the structure (DNRT_SIZEOF) ID - net ID to get info about RESULTS success - TRUE (-1) if success, otherwise FALSE NOTES EXAMPLE BUGS SEE ALSO RTHighestID(), RTNumberofNets(), dignet/dignet.i|h dignet.library/RTNumberofNets dignet.library/RTNumberofNets NAME RTNumberofNets -- Returns number of open nets (version 3) SYNOPSIS number=RTNumberofNets() ULONG RTNumberofNets(void); FUNCTION This function will return number of open nets in the system. You should use the RTCheck to find out any mismatch in the net count and resource trackers counter. RESULTS number - number of nets open NOTES This function doesn't return the highest available number of nets. Use the function RTHighestID() to find that out. EXAMPLE BUGS SEE ALSO RTCheck(), RTHighestID()